<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>NVTX C++ API Reference: NVTX C++ API Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">NVTX C++ API Reference<span id="projectnumber">&#160;1.0</span>
   </div>
   <div id="projectbrief">C++ convenience wrappers for NVTX v3 C API</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.8 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

<div><div class="header">
  <div class="headertitle"><div class="title">NVTX C++ API Reference </div></div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#QUICK_START">Quick Start</a></li>
<li class="level1"><a href="#Overview">Overview</a></li>
<li class="level1"><a href="#RANGES">Ranges</a><ul><li class="level2"><a href="#scoped_range">Scoped Range</a></li>
<li class="level2"><a href="#unique_range">Unique Range</a></li>
</ul>
</li>
<li class="level1"><a href="#MARKS">Marks</a></li>
<li class="level1"><a href="#DOMAINS">Domains</a></li>
<li class="level1"><a href="#ATTRIBUTES">Event Attributes</a><ul><li class="level2"><a href="#MESSAGES">message</a><ul><li class="level3"><a href="#REGISTERED_MESSAGE">Registered Messages</a></li>
</ul>
</li>
<li class="level2"><a href="#COLOR">color</a></li>
<li class="level2"><a href="#CATEGORY">category</a><ul><li class="level3"><a href="#NAMED_CATEGORIES">Named Categories</a></li>
</ul>
</li>
<li class="level2"><a href="#PAYLOAD">payload</a></li>
</ul>
</li>
<li class="level1"><a href="#EXAMPLE">Example</a></li>
<li class="level1"><a href="#MACROS">Convenience Macros</a></li>
</ul>
</div>
<div class="textblock"><h1><a class="anchor" id="QUICK_START"></a>
Quick Start</h1>
<p>To add NVTX ranges to your code, use the <code>nvtx3::scoped_range</code> RAII object. A range begins when the object is created, and ends when the object is destroyed.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &quot;<a class="code" href="nvtx3_8hpp.html">nvtx3/nvtx3.hpp</a>&quot;</span></div>
<div class="line"><span class="keywordtype">void</span> some_function() {</div>
<div class="line">   <span class="comment">// Begins a NVTX range with the message &quot;some_function&quot;</span></div>
<div class="line">   <span class="comment">// The range ends when some_function() returns and `r` is destroyed</span></div>
<div class="line">   nvtx3::scoped_range r{<span class="stringliteral">&quot;some_function&quot;</span>};</div>
<div class="line"> </div>
<div class="line">   <span class="keywordflow">for</span>(<span class="keywordtype">int</span> i = 0; i &lt; 5; ++i) {</div>
<div class="line">      nvtx3::scoped_range loop{<span class="stringliteral">&quot;loop range&quot;</span>};</div>
<div class="line">      std::this_thread::sleep_for(std::chrono::seconds{1});</div>
<div class="line">   }</div>
<div class="line">} <span class="comment">// Range ends when `r` is destroyed</span></div>
<div class="ttc" id="anvtx3_8hpp_html"><div class="ttname"><a href="nvtx3_8hpp.html">nvtx3.hpp</a></div><div class="ttdoc">Provides C++ constructs making the NVTX library safer and easier to use with zero overhead.</div></div>
</div><!-- fragment --><p>The example code above generates the following timeline view in Nsight Systems:</p>
<div class="image">
<img src="https://raw.githubusercontent.com/NVIDIA/NVTX/release-v3/docs/images/example_range.png" alt=""/>
</div>
<p>Alternatively, use the <a class="el" href="index.html#MACROS">Convenience Macros</a> like <code>NVTX3_FUNC_RANGE()</code> to add ranges to your code that automatically use the name of the enclosing function as the range's message.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &quot;<a class="code" href="nvtx3_8hpp.html">nvtx3/nvtx3.hpp</a>&quot;</span></div>
<div class="line"><span class="keywordtype">void</span> some_function() {</div>
<div class="line">   <span class="comment">// Creates a range with a message &quot;some_function&quot; that ends when the</span></div>
<div class="line">   <span class="comment">// enclosing function returns</span></div>
<div class="line">   NVTX3_FUNC_RANGE();</div>
<div class="line">   ...</div>
<div class="line">}</div>
</div><!-- fragment --><h1><a class="anchor" id="Overview"></a>
Overview</h1>
<p>The NVTX library provides a set of functions for users to annotate their code to aid in performance profiling and optimization. These annotations provide information to tools like Nsight Systems to improve visualization of application timelines.</p>
<p><a class="el" href="index.html#RANGES">Ranges</a> are one of the most commonly used NVTX constructs for annotating a span of time. For example, imagine a user wanted to see every time a function, <code>my_function</code>, is called and how long it takes to execute. This can be accomplished with an NVTX range created on the entry to the function and terminated on return from <code>my_function</code> using the push/pop C APIs:</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> my_function(...) {</div>
<div class="line">   nvtxRangePushA(<span class="stringliteral">&quot;my_function&quot;</span>); <span class="comment">// Begins NVTX range</span></div>
<div class="line">   <span class="comment">// do work</span></div>
<div class="line">   nvtxRangePop(); <span class="comment">// Ends NVTX range</span></div>
<div class="line">}</div>
</div><!-- fragment --><p>One of the challenges with using the NVTX C API is that it requires manually terminating the end of the range with <code>nvtxRangePop</code>. This can be challenging if <code>my_function()</code> has multiple returns or can throw exceptions as it requires calling <code>nvtxRangePop()</code> before all possible return points.</p>
<p>NVTX C++ solves this inconvenience through the "RAII" technique by providing a <code>nvtx3::scoped_range</code> class that begins a range at construction and ends the range on destruction. The above example then becomes:</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> my_function(...) {</div>
<div class="line">   nvtx3::scoped_range r{<span class="stringliteral">&quot;my_function&quot;</span>}; <span class="comment">// Begins NVTX range</span></div>
<div class="line">   <span class="comment">// do work</span></div>
<div class="line">} <span class="comment">// Range ends on exit from `my_function` when `r` is destroyed</span></div>
</div><!-- fragment --><p>The range object <code>r</code> is deterministically destroyed whenever <code>my_function</code> returns&mdash;ending the NVTX range without manual intervention. For more information, see <a class="el" href="index.html#RANGES">Ranges</a> and <code><a class="el" href="classnvtx3_1_1v1_1_1scoped__range__in.html" title="A RAII object for creating a NVTX range local to a thread within a domain.">nvtx3::scoped_range_in</a></code>.</p>
<p>Another inconvenience of the NVTX C APIs are the several constructs where the user is expected to initialize an object at the beginning of an application and reuse that object throughout the lifetime of the application. For example see domains, categories, and registered messages.</p>
<p>Example: </p><div class="fragment"><div class="line">nvtxDomainHandle_t D = nvtxDomainCreateA(<span class="stringliteral">&quot;my domain&quot;</span>);</div>
<div class="line"><span class="comment">// Reuse `D` throughout the rest of the application</span></div>
</div><!-- fragment --><p>This can be problematic if the user application or library does not have an explicit initialization function called before all other functions to ensure that these long-lived objects are initialized before being used.</p>
<p>NVTX C++ makes use of the "construct on first use" technique to alleviate this inconvenience. In short, a function local static object is constructed upon the first invocation of a function and returns a reference to that object on all future invocations. See the documentation for <code><a class="el" href="classnvtx3_1_1v1_1_1domain.html" title="domains allow for grouping NVTX events into a single scope to differentiate them from events in other...">nvtx3::domain</a></code>, <code>nvtx3::named_category</code>, <code>nvtx3::registered_string</code>, and <a href="https://isocpp.org/wiki/faq/ctors#static-init-order-on-first-use">https://isocpp.org/wiki/faq/ctors#static-init-order-on-first-use</a> for more information.</p>
<p>Using construct on first use, the above example becomes: </p><div class="fragment"><div class="line"><span class="keyword">struct </span>my_domain{ <span class="keyword">static</span> <span class="keyword">constexpr</span> <span class="keywordtype">char</span> <span class="keyword">const</span>* name{<span class="stringliteral">&quot;my domain&quot;</span>}; };</div>
<div class="line"> </div>
<div class="line"><span class="comment">// The first invocation of `domain::get` for the type `my_domain` will</span></div>
<div class="line"><span class="comment">// construct a `nvtx3::domain` object and return a reference to it. Future</span></div>
<div class="line"><span class="comment">// invocations simply return a reference.</span></div>
<div class="line"><a class="code hl_class" href="classnvtx3_1_1v1_1_1domain.html">nvtx3::domain</a> <span class="keyword">const</span>&amp; D = nvtx3::domain::get&lt;my_domain&gt;();</div>
<div class="ttc" id="aclassnvtx3_1_1v1_1_1domain_html"><div class="ttname"><a href="classnvtx3_1_1v1_1_1domain.html">nvtx3::domain</a></div><div class="ttdoc">domains allow for grouping NVTX events into a single scope to differentiate them from events in other...</div><div class="ttdef"><b>Definition</b> <a href="nvtx3_8hpp_source.html#l00769">nvtx3.hpp:769</a></div></div>
</div><!-- fragment --><p> For more information about NVTX and how it can be used, see <a href="https://docs.nvidia.com/cuda/profiler-users-guide/index.html#nvtx">https://docs.nvidia.com/cuda/profiler-users-guide/index.html#nvtx</a> and <a href="https://devblogs.nvidia.com/cuda-pro-tip-generate-custom-application-profile-timelines-nvtx/">https://devblogs.nvidia.com/cuda-pro-tip-generate-custom-application-profile-timelines-nvtx/</a> for more information.</p>
<h1><a class="anchor" id="RANGES"></a>
Ranges</h1>
<p>Ranges are used to describe a span of time during the execution of an application. Common examples are using ranges to annotate the time it takes to execute a function or an iteration of a loop.</p>
<p>NVTX C++ uses RAII to automate the generation of ranges that are tied to the lifetime of objects. Similar to <code>std::lock_guard</code> in the C++ Standard Template Library.</p>
<h2><a class="anchor" id="scoped_range"></a>
Scoped Range</h2>
<p><code><a class="el" href="classnvtx3_1_1v1_1_1scoped__range__in.html" title="A RAII object for creating a NVTX range local to a thread within a domain.">nvtx3::scoped_range_in</a></code> is a class that begins a range upon construction and ends the range at destruction. This is one of the most commonly used constructs in NVTX C++ and is useful for annotating spans of time on a particular thread. These ranges can be nested to arbitrary depths.</p>
<p><code>nvtx3::scoped_range</code> is an alias for a <code><a class="el" href="classnvtx3_1_1v1_1_1scoped__range__in.html" title="A RAII object for creating a NVTX range local to a thread within a domain.">nvtx3::scoped_range_in</a></code> in the global NVTX domain. For more information about Domains, see <a class="el" href="index.html#DOMAINS">Domains</a>.</p>
<p>Various attributes of a range can be configured constructing a <code><a class="el" href="classnvtx3_1_1v1_1_1scoped__range__in.html" title="A RAII object for creating a NVTX range local to a thread within a domain.">nvtx3::scoped_range_in</a></code> with a <code><a class="el" href="classnvtx3_1_1v1_1_1event__attributes.html" title="Describes the attributes of a NVTX event.">nvtx3::event_attributes</a></code> object. For more information, see <a class="el" href="index.html#ATTRIBUTES">Event Attributes</a>.</p>
<p>Example:</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> some_function() {</div>
<div class="line">   <span class="comment">// Creates a range for the duration of `some_function`</span></div>
<div class="line">   nvtx3::scoped_range r{};</div>
<div class="line"> </div>
<div class="line">   <span class="keywordflow">while</span>(<span class="keyword">true</span>) {</div>
<div class="line">      <span class="comment">// Creates a range for every loop iteration</span></div>
<div class="line">      <span class="comment">// `loop_range` is nested inside `r`</span></div>
<div class="line">      nvtx3::scoped_range loop_range{};</div>
<div class="line">   }</div>
<div class="line">}</div>
</div><!-- fragment --><h2><a class="anchor" id="unique_range"></a>
Unique Range</h2>
<p><code>nvtx3::unique_range</code> is similar to <code>nvtx3::scoped_range</code>, with a few key differences:</p><ul>
<li><code>unique_range</code> objects can be destroyed in any order whereas <code>scoped_range</code> objects must be destroyed in exact reverse creation order</li>
<li><code>unique_range</code> can start and end on different threads</li>
<li><code>unique_range</code> is movable</li>
<li><code>unique_range</code> objects can be constructed as heap objects</li>
</ul>
<p>There is extra overhead associated with <code>unique_range</code> constructs and therefore use of <code><a class="el" href="classnvtx3_1_1v1_1_1scoped__range__in.html" title="A RAII object for creating a NVTX range local to a thread within a domain.">nvtx3::scoped_range_in</a></code> should be preferred.</p>
<h1><a class="anchor" id="MARKS"></a>
Marks</h1>
<p><code>nvtx3::mark</code> annotates an instantaneous point in time with a "marker".</p>
<p>Unlike a "range" which has a beginning and an end, a marker is a single event in an application, such as detecting a problem:</p>
<div class="fragment"><div class="line"><span class="keywordtype">bool</span> success = do_operation(...);</div>
<div class="line"><span class="keywordflow">if</span> (!success) {</div>
<div class="line">   nvtx3::mark(<span class="stringliteral">&quot;operation failed!&quot;</span>);</div>
<div class="line">}</div>
</div><!-- fragment --><h1><a class="anchor" id="DOMAINS"></a>
Domains</h1>
<p>Similar to C++ namespaces, domains allow for scoping NVTX events. By default, all NVTX events belong to the "global" domain. Libraries and applications should scope their events to use a custom domain to differentiate where the events originate from.</p>
<p>It is common for a library or application to have only a single domain and for the name of that domain to be known at compile time. Therefore, Domains in NVTX C++ are represented by <em>tag types</em>.</p>
<p>For example, to define a custom domain, simply define a new concrete type (a <code>class</code> or <code>struct</code>) with a <code>static</code> member called <code>name</code> that contains the desired name of the domain.</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>my_domain{ <span class="keyword">static</span> <span class="keyword">constexpr</span> <span class="keywordtype">char</span> <span class="keyword">const</span>* name{<span class="stringliteral">&quot;my domain&quot;</span>}; };</div>
</div><!-- fragment --><p>For any NVTX C++ construct that can be scoped to a domain, the type <code>my_domain</code> can be passed as an explicit template argument to scope it to the custom domain.</p>
<p>The tag type <code>nvtx3::domain::global</code> represents the global NVTX domain.</p>
<div class="fragment"><div class="line"><span class="comment">// By default, `scoped_range_in` belongs to the global domain</span></div>
<div class="line"><a class="code hl_class" href="classnvtx3_1_1v1_1_1scoped__range__in.html">nvtx3::scoped_range_in&lt;&gt;</a> r0{};</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Alias for a `scoped_range_in` in the global domain</span></div>
<div class="line">nvtx3::scoped_range r1{};</div>
<div class="line"> </div>
<div class="line"><span class="comment">// `r` belongs to the custom domain</span></div>
<div class="line"><a class="code hl_class" href="classnvtx3_1_1v1_1_1scoped__range__in.html">nvtx3::scoped_range_in&lt;my_domain&gt;</a> r{};</div>
<div class="ttc" id="aclassnvtx3_1_1v1_1_1scoped__range__in_html"><div class="ttname"><a href="classnvtx3_1_1v1_1_1scoped__range__in.html">nvtx3::scoped_range_in</a></div><div class="ttdoc">A RAII object for creating a NVTX range local to a thread within a domain.</div><div class="ttdef"><b>Definition</b> <a href="nvtx3_8hpp_source.html#l02101">nvtx3.hpp:2101</a></div></div>
</div><!-- fragment --><p>When using a custom domain, it is recommended to define type aliases for NVTX constructs in the custom domain. </p><div class="fragment"><div class="line"><span class="keyword">using </span>my_scoped_range = <a class="code hl_class" href="classnvtx3_1_1v1_1_1scoped__range__in.html">nvtx3::scoped_range_in&lt;my_domain&gt;</a>;</div>
<div class="line"><span class="keyword">using </span>my_registered_string = <a class="code hl_class" href="classnvtx3_1_1v1_1_1registered__string__in.html">nvtx3::registered_string_in&lt;my_domain&gt;</a>;</div>
<div class="line"><span class="keyword">using </span>my_named_category = <a class="code hl_class" href="classnvtx3_1_1v1_1_1named__category__in.html">nvtx3::named_category_in&lt;my_domain&gt;</a>;</div>
<div class="ttc" id="aclassnvtx3_1_1v1_1_1named__category__in_html"><div class="ttname"><a href="classnvtx3_1_1v1_1_1named__category__in.html">nvtx3::named_category_in</a></div><div class="ttdoc">A category with an associated name string.</div><div class="ttdef"><b>Definition</b> <a href="nvtx3_8hpp_source.html#l01249">nvtx3.hpp:1249</a></div></div>
<div class="ttc" id="aclassnvtx3_1_1v1_1_1registered__string__in_html"><div class="ttname"><a href="classnvtx3_1_1v1_1_1registered__string__in.html">nvtx3::registered_string_in</a></div><div class="ttdoc">A message registered with NVTX.</div><div class="ttdef"><b>Definition</b> <a href="nvtx3_8hpp_source.html#l01449">nvtx3.hpp:1449</a></div></div>
</div><!-- fragment --><p>See <code><a class="el" href="classnvtx3_1_1v1_1_1domain.html" title="domains allow for grouping NVTX events into a single scope to differentiate them from events in other...">nvtx3::domain</a></code> for more information.</p>
<h1><a class="anchor" id="ATTRIBUTES"></a>
Event Attributes</h1>
<p>NVTX events can be customized with various attributes to provide additional information (such as a custom message) or to control visualization of the event (such as the color used). These attributes can be specified per-event via arguments to a <code><a class="el" href="classnvtx3_1_1v1_1_1event__attributes.html" title="Describes the attributes of a NVTX event.">nvtx3::event_attributes</a></code> object.</p>
<p>NVTX events can be customized via four "attributes":</p><ul>
<li><a class="el" href="index.html#COLOR">color</a> : color used to visualize the event in tools.</li>
<li><a class="el" href="index.html#MESSAGES">message</a> : Custom message string.</li>
<li><a class="el" href="index.html#PAYLOAD">payload</a> : User-defined numerical value.</li>
<li><a class="el" href="index.html#CATEGORY">category</a> : Intra-domain grouping.</li>
</ul>
<p>It is possible to construct a <code><a class="el" href="classnvtx3_1_1v1_1_1event__attributes.html" title="Describes the attributes of a NVTX event.">nvtx3::event_attributes</a></code> from any number of attribute objects (<a class="el" href="classnvtx3_1_1v1_1_1color.html" title="Represents a custom color that can be associated with an NVTX event via its event_attributes.">nvtx3::color</a>, <a class="el" href="classnvtx3_1_1v1_1_1message.html" title="Allows associating a message string with an NVTX event via its EventAttributes.">nvtx3::message</a>, <a class="el" href="classnvtx3_1_1v1_1_1payload.html" title="A numerical value that can be associated with an NVTX event via its event_attributes.">nvtx3::payload</a>, <a class="el" href="classnvtx3_1_1v1_1_1category.html" title="Object for intra-domain grouping of NVTX events.">nvtx3::category</a>) in any order. If an attribute is not specified, a tool specific default value is used. See <code><a class="el" href="classnvtx3_1_1v1_1_1event__attributes.html" title="Describes the attributes of a NVTX event.">nvtx3::event_attributes</a></code> for more information.</p>
<div class="fragment"><div class="line"><span class="comment">// Set message, same as passing nvtx3::message{&quot;message&quot;}</span></div>
<div class="line"><a class="code hl_class" href="classnvtx3_1_1v1_1_1event__attributes.html">nvtx3::event_attributes</a> attr{<span class="stringliteral">&quot;message&quot;</span>};</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Set message and color</span></div>
<div class="line"><a class="code hl_class" href="classnvtx3_1_1v1_1_1event__attributes.html">nvtx3::event_attributes</a> attr{<span class="stringliteral">&quot;message&quot;</span>, <a class="code hl_struct" href="structnvtx3_1_1v1_1_1rgb.html">nvtx3::rgb</a>{127, 255, 0}};</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Set message, color, payload, category</span></div>
<div class="line"><a class="code hl_class" href="classnvtx3_1_1v1_1_1event__attributes.html">nvtx3::event_attributes</a> attr{<span class="stringliteral">&quot;message&quot;</span>,</div>
<div class="line">                             <a class="code hl_struct" href="structnvtx3_1_1v1_1_1rgb.html">nvtx3::rgb</a>{127, 255, 0},</div>
<div class="line">                             <a class="code hl_class" href="classnvtx3_1_1v1_1_1payload.html">nvtx3::payload</a>{42},</div>
<div class="line">                             <a class="code hl_class" href="classnvtx3_1_1v1_1_1category.html">nvtx3::category</a>{1}};</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Same as above -- can use any order of arguments</span></div>
<div class="line"><a class="code hl_class" href="classnvtx3_1_1v1_1_1event__attributes.html">nvtx3::event_attributes</a> attr{<a class="code hl_class" href="classnvtx3_1_1v1_1_1payload.html">nvtx3::payload</a>{42},</div>
<div class="line">                             <a class="code hl_class" href="classnvtx3_1_1v1_1_1category.html">nvtx3::category</a>{1},</div>
<div class="line">                             <span class="stringliteral">&quot;message&quot;</span>,</div>
<div class="line">                             <a class="code hl_struct" href="structnvtx3_1_1v1_1_1rgb.html">nvtx3::rgb</a>{127, 255, 0}};</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Multiple arguments of the same type are allowed, but only the first is</span></div>
<div class="line"><span class="comment">// used -- in this example, payload is set to 42:</span></div>
<div class="line"><a class="code hl_class" href="classnvtx3_1_1v1_1_1event__attributes.html">nvtx3::event_attributes</a> attr{ <a class="code hl_class" href="classnvtx3_1_1v1_1_1payload.html">nvtx3::payload</a>{42}, <a class="code hl_class" href="classnvtx3_1_1v1_1_1payload.html">nvtx3::payload</a>{7} };</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Using the nvtx3 namespace in a local scope makes the syntax more succinct:</span></div>
<div class="line"><span class="keyword">using namespace </span>nvtx3;</div>
<div class="line"><a class="code hl_class" href="classnvtx3_1_1v1_1_1event__attributes.html">event_attributes</a> attr{<span class="stringliteral">&quot;message&quot;</span>, <a class="code hl_struct" href="structnvtx3_1_1v1_1_1rgb.html">rgb</a>{127, 255, 0}, <a class="code hl_class" href="classnvtx3_1_1v1_1_1payload.html">payload</a>{42}, <a class="code hl_class" href="classnvtx3_1_1v1_1_1category.html">category</a>{1}};</div>
<div class="ttc" id="aclassnvtx3_1_1v1_1_1category_html"><div class="ttname"><a href="classnvtx3_1_1v1_1_1category.html">nvtx3::category</a></div><div class="ttdoc">Object for intra-domain grouping of NVTX events.</div><div class="ttdef"><b>Definition</b> <a href="nvtx3_8hpp_source.html#l01166">nvtx3.hpp:1166</a></div></div>
<div class="ttc" id="aclassnvtx3_1_1v1_1_1event__attributes_html"><div class="ttname"><a href="classnvtx3_1_1v1_1_1event__attributes.html">nvtx3::event_attributes</a></div><div class="ttdoc">Describes the attributes of a NVTX event.</div><div class="ttdef"><b>Definition</b> <a href="nvtx3_8hpp_source.html#l01954">nvtx3.hpp:1954</a></div></div>
<div class="ttc" id="aclassnvtx3_1_1v1_1_1payload_html"><div class="ttname"><a href="classnvtx3_1_1v1_1_1payload.html">nvtx3::payload</a></div><div class="ttdoc">A numerical value that can be associated with an NVTX event via its event_attributes.</div><div class="ttdef"><b>Definition</b> <a href="nvtx3_8hpp_source.html#l01794">nvtx3.hpp:1794</a></div></div>
<div class="ttc" id="astructnvtx3_1_1v1_1_1rgb_html"><div class="ttname"><a href="structnvtx3_1_1v1_1_1rgb.html">nvtx3::rgb</a></div><div class="ttdoc">Indicates the values of the red, green, and blue color channels for an RGB color to use as an event a...</div><div class="ttdef"><b>Definition</b> <a href="nvtx3_8hpp_source.html#l00993">nvtx3.hpp:993</a></div></div>
</div><!-- fragment --><h2><a class="anchor" id="MESSAGES"></a>
message</h2>
<p><code><a class="el" href="classnvtx3_1_1v1_1_1message.html" title="Allows associating a message string with an NVTX event via its EventAttributes.">nvtx3::message</a></code> sets the message string for an NVTX event.</p>
<p>Example: </p><div class="fragment"><div class="line"><span class="comment">// Create an `event_attributes` with the message &quot;my message&quot;</span></div>
<div class="line"><a class="code hl_class" href="classnvtx3_1_1v1_1_1event__attributes.html">nvtx3::event_attributes</a> attr{<a class="code hl_class" href="classnvtx3_1_1v1_1_1message.html">nvtx3::message</a>{<span class="stringliteral">&quot;my message&quot;</span>}};</div>
<div class="line"> </div>
<div class="line"><span class="comment">// strings and string literals implicitly assumed to be a `nvtx3::message`</span></div>
<div class="line"><a class="code hl_class" href="classnvtx3_1_1v1_1_1event__attributes.html">nvtx3::event_attributes</a> attr{<span class="stringliteral">&quot;my message&quot;</span>};</div>
<div class="ttc" id="aclassnvtx3_1_1v1_1_1message_html"><div class="ttname"><a href="classnvtx3_1_1v1_1_1message.html">nvtx3::message</a></div><div class="ttdoc">Allows associating a message string with an NVTX event via its EventAttributes.</div><div class="ttdef"><b>Definition</b> <a href="nvtx3_8hpp_source.html#l01664">nvtx3.hpp:1664</a></div></div>
</div><!-- fragment --><h3><a class="anchor" id="REGISTERED_MESSAGE"></a>
Registered Messages</h3>
<p>Associating a <code><a class="el" href="classnvtx3_1_1v1_1_1message.html" title="Allows associating a message string with an NVTX event via its EventAttributes.">nvtx3::message</a></code> with an event requires copying the contents of the message every time the message is used, i.e., copying the entire message string. This may cause non-trivial overhead in performance sensitive code.</p>
<p>To eliminate this overhead, NVTX allows registering a message string, yielding a "handle" that is inexpensive to copy that may be used in place of a message string. When visualizing the events, tools such as Nsight Systems will take care of mapping the message handle to its string.</p>
<p>A message should be registered once and the handle reused throughout the rest of the application. This can be done by either explicitly creating static <code>nvtx3::registered_string</code> objects, or using the <code>nvtx3::registered_string::get</code> construct on first use helper (recommended).</p>
<p>Similar to <a class="el" href="index.html#DOMAINS">Domains</a>, <code>nvtx3::registered_string::get</code> requires defining a custom tag type with a static <code>message</code> member whose value will be the contents of the registered string.</p>
<p>Example: </p><div class="fragment"><div class="line"><span class="comment">// Explicitly constructed, static `registered_string` in my_domain:</span></div>
<div class="line"><span class="keyword">static</span> <a class="code hl_class" href="classnvtx3_1_1v1_1_1registered__string__in.html">registered_string_in&lt;my_domain&gt;</a> static_message{<span class="stringliteral">&quot;my message&quot;</span>};</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Or use construct on first use:</span></div>
<div class="line"><span class="comment">// Define a tag type with a `message` member string to register</span></div>
<div class="line"><span class="keyword">struct </span>my_message{ <span class="keyword">static</span> <span class="keyword">constexpr</span> <span class="keywordtype">char</span> <span class="keyword">const</span>* <a class="code hl_class" href="classnvtx3_1_1v1_1_1message.html">message</a>{ <span class="stringliteral">&quot;my message&quot;</span> }; };</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Uses construct on first use to register the contents of</span></div>
<div class="line"><span class="comment">// `my_message::message`</span></div>
<div class="line"><span class="keyword">auto</span>&amp; msg = <a class="code hl_class" href="classnvtx3_1_1v1_1_1registered__string__in.html">nvtx3::registered_string_in&lt;my_domain&gt;::get&lt;my_message&gt;</a>();</div>
</div><!-- fragment --><h2><a class="anchor" id="COLOR"></a>
color</h2>
<p>Associating a <code><a class="el" href="classnvtx3_1_1v1_1_1color.html" title="Represents a custom color that can be associated with an NVTX event via its event_attributes.">nvtx3::color</a></code> with an event allows controlling how the event is visualized in a tool such as Nsight Systems. This is a convenient way to visually differentiate among different events.</p>
<div class="fragment"><div class="line"><span class="comment">// Define a color via rgb color values</span></div>
<div class="line"><a class="code hl_class" href="classnvtx3_1_1v1_1_1color.html">nvtx3::color</a> c{<a class="code hl_struct" href="structnvtx3_1_1v1_1_1rgb.html">nvtx3::rgb</a>{127, 255, 0}};</div>
<div class="line"><a class="code hl_class" href="classnvtx3_1_1v1_1_1event__attributes.html">nvtx3::event_attributes</a> attr{c};</div>
<div class="line"> </div>
<div class="line"><span class="comment">// rgb color values can be passed directly to an `event_attributes`</span></div>
<div class="line"><a class="code hl_class" href="classnvtx3_1_1v1_1_1event__attributes.html">nvtx3::event_attributes</a> attr1{<a class="code hl_struct" href="structnvtx3_1_1v1_1_1rgb.html">nvtx3::rgb</a>{127,255,0}};</div>
<div class="ttc" id="aclassnvtx3_1_1v1_1_1color_html"><div class="ttname"><a href="classnvtx3_1_1v1_1_1color.html">nvtx3::color</a></div><div class="ttdoc">Represents a custom color that can be associated with an NVTX event via its event_attributes.</div><div class="ttdef"><b>Definition</b> <a href="nvtx3_8hpp_source.html#l01059">nvtx3.hpp:1059</a></div></div>
</div><!-- fragment --><h2><a class="anchor" id="CATEGORY"></a>
category</h2>
<p>A <code><a class="el" href="classnvtx3_1_1v1_1_1category.html" title="Object for intra-domain grouping of NVTX events.">nvtx3::category</a></code> is simply an integer id that allows for fine-grain grouping of NVTX events. For example, one might use separate categories for IO, memory allocation, compute, etc.</p>
<div class="fragment"><div class="line"><a class="code hl_class" href="classnvtx3_1_1v1_1_1event__attributes.html">nvtx3::event_attributes</a>{<a class="code hl_class" href="classnvtx3_1_1v1_1_1category.html">nvtx3::category</a>{1}};</div>
</div><!-- fragment --><h3><a class="anchor" id="NAMED_CATEGORIES"></a>
Named Categories</h3>
<p>Associates a <code>name</code> string with a category <code>id</code> to help differentiate among categories.</p>
<p>For any given category id <code>Id</code>, a <code>named_category{Id, "name"}</code> should only be constructed once and reused throughout an application. This can be done by either explicitly creating static <code>nvtx3::named_category</code> objects, or using the <code>nvtx3::named_category::get</code> construct on first use helper (recommended).</p>
<p>Similar to <a class="el" href="index.html#DOMAINS">Domains</a>, <code>nvtx3::named_category::get</code> requires defining a custom tag type with static <code>name</code> and <code>id</code> members.</p>
<div class="fragment"><div class="line"><span class="comment">// Explicitly constructed, static `named_category` in my_domain:</span></div>
<div class="line"><span class="keyword">static</span> <a class="code hl_class" href="classnvtx3_1_1v1_1_1named__category__in.html">nvtx3::named_category_in&lt;my_domain&gt;</a> static_category{42, <span class="stringliteral">&quot;my category&quot;</span>};</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Or use construct on first use:</span></div>
<div class="line"><span class="comment">// Define a tag type with `name` and `id` members</span></div>
<div class="line"><span class="keyword">struct </span>my_category {</div>
<div class="line">   <span class="keyword">static</span> <span class="keyword">constexpr</span> <span class="keywordtype">char</span> <span class="keyword">const</span>* name{<span class="stringliteral">&quot;my category&quot;</span>}; <span class="comment">// category name</span></div>
<div class="line">   <span class="keyword">static</span> <span class="keyword">constexpr</span> uint32_t <span class="keywordtype">id</span>{42}; <span class="comment">// category id</span></div>
<div class="line">};</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Use construct on first use to name the category id `42`</span></div>
<div class="line"><span class="comment">// with name &quot;my category&quot;:</span></div>
<div class="line"><span class="keyword">auto</span>&amp; cat = <a class="code hl_class" href="classnvtx3_1_1v1_1_1named__category__in.html">named_category_in&lt;my_domain&gt;::get&lt;my_category&gt;</a>();</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Range `r` associated with category id `42`</span></div>
<div class="line"><a class="code hl_class" href="classnvtx3_1_1v1_1_1event__attributes.html">nvtx3::event_attributes</a> attr{cat};</div>
</div><!-- fragment --><h2><a class="anchor" id="PAYLOAD"></a>
payload</h2>
<p>Allows associating a user-defined numerical value with an event.</p>
<div class="fragment"><div class="line"><span class="comment">// Constructs a payload from the `int32_t` value 42</span></div>
<div class="line">nvtx3:: event_attributes attr{<a class="code hl_class" href="classnvtx3_1_1v1_1_1payload.html">nvtx3::payload</a>{42}};</div>
</div><!-- fragment --><h1><a class="anchor" id="EXAMPLE"></a>
Example</h1>
<p>Putting it all together: </p><div class="fragment"><div class="line"><span class="comment">// Define a custom domain tag type</span></div>
<div class="line"><span class="keyword">struct </span>my_domain{ <span class="keyword">static</span> <span class="keyword">constexpr</span> <span class="keywordtype">char</span> <span class="keyword">const</span>* name{<span class="stringliteral">&quot;my domain&quot;</span>}; };</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Define a named category tag type</span></div>
<div class="line"><span class="keyword">struct </span>my_category{</div>
<div class="line">   <span class="keyword">static</span> <span class="keyword">constexpr</span> <span class="keywordtype">char</span> <span class="keyword">const</span>* name{<span class="stringliteral">&quot;my category&quot;</span>};</div>
<div class="line">   <span class="keyword">static</span> <span class="keyword">constexpr</span> uint32_t <span class="keywordtype">id</span>{42};</div>
<div class="line">};</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Define a registered string tag type</span></div>
<div class="line"><span class="keyword">struct </span>my_message{ <span class="keyword">static</span> <span class="keyword">constexpr</span> <span class="keywordtype">char</span> <span class="keyword">const</span>* <a class="code hl_class" href="classnvtx3_1_1v1_1_1message.html">message</a>{<span class="stringliteral">&quot;my message&quot;</span>}; };</div>
<div class="line"> </div>
<div class="line"><span class="comment">// For convenience, use aliases for domain scoped objects</span></div>
<div class="line"><span class="keyword">using </span>my_scoped_range = <a class="code hl_class" href="classnvtx3_1_1v1_1_1scoped__range__in.html">nvtx3::scoped_range_in&lt;my_domain&gt;</a>;</div>
<div class="line"><span class="keyword">using </span>my_registered_string = <a class="code hl_class" href="classnvtx3_1_1v1_1_1registered__string__in.html">nvtx3::registered_string_in&lt;my_domain&gt;</a>;</div>
<div class="line"><span class="keyword">using </span>my_named_category = <a class="code hl_class" href="classnvtx3_1_1v1_1_1named__category__in.html">nvtx3::named_category_in&lt;my_domain&gt;</a>;</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Default values for all attributes</span></div>
<div class="line"><a class="code hl_class" href="classnvtx3_1_1v1_1_1event__attributes.html">nvtx3::event_attributes</a> attr{};</div>
<div class="line">my_scoped_range r0{attr};</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Custom (unregistered) message, and unnamed category</span></div>
<div class="line"><a class="code hl_class" href="classnvtx3_1_1v1_1_1event__attributes.html">nvtx3::event_attributes</a> attr1{<span class="stringliteral">&quot;message&quot;</span>, <a class="code hl_class" href="classnvtx3_1_1v1_1_1category.html">nvtx3::category</a>{2}};</div>
<div class="line">my_scoped_range r1{attr1};</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Alternatively, pass arguments of `event_attributes` constructor directly</span></div>
<div class="line"><span class="comment">// to `my_scoped_range`</span></div>
<div class="line">my_scoped_range r2{<span class="stringliteral">&quot;message&quot;</span>, <a class="code hl_class" href="classnvtx3_1_1v1_1_1category.html">nvtx3::category</a>{2}};</div>
<div class="line"> </div>
<div class="line"><span class="comment">// construct on first use a registered string</span></div>
<div class="line"><span class="keyword">auto</span>&amp; msg = my_registered_string::get&lt;my_message&gt;();</div>
<div class="line"> </div>
<div class="line"><span class="comment">// construct on first use a named category</span></div>
<div class="line"><span class="keyword">auto</span>&amp; cat = my_named_category::get&lt;my_category&gt;();</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Use registered string and named category with a custom payload</span></div>
<div class="line">my_scoped_range r3{msg, cat, <a class="code hl_class" href="classnvtx3_1_1v1_1_1payload.html">nvtx3::payload</a>{42}};</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Any number of arguments in any order</span></div>
<div class="line">my_scoped_range r{<a class="code hl_struct" href="structnvtx3_1_1v1_1_1rgb.html">nvtx3::rgb</a>{127, 255, 0}, msg};</div>
</div><!-- fragment --> <h1><a class="anchor" id="MACROS"></a>
Convenience Macros</h1>
<p>Oftentimes users want to quickly and easily add NVTX ranges to their library or application to aid in profiling and optimization.</p>
<p>A convenient way to do this is to use the NVTX3_FUNC_RANGE and NVTX3_FUNC_RANGE_IN macros. These macros take care of constructing an <code><a class="el" href="classnvtx3_1_1v1_1_1scoped__range__in.html" title="A RAII object for creating a NVTX range local to a thread within a domain.">nvtx3::scoped_range_in</a></code> with the name of the enclosing function as the range's message.</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> some_function() {</div>
<div class="line">   <span class="comment">// Automatically generates an NVTX range for the duration of the function</span></div>
<div class="line">   <span class="comment">// using &quot;some_function&quot; as the event&#39;s message.</span></div>
<div class="line">   NVTX3_FUNC_RANGE();</div>
<div class="line">}</div>
</div><!-- fragment --> </div></div><!-- PageDoc -->
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.8
</small></address>
</body>
</html>
